json-schema-to-typescript

What is json-schema-to-typescript?

The json-schema-to-typescript npm package is a tool that converts JSON Schema definitions into TypeScript interfaces. This is particularly useful for ensuring type safety in TypeScript projects by generating types directly from JSON Schema, which can help in maintaining consistency between your data models and TypeScript types.

What are json-schema-to-typescript's main functionalities?

Convert JSON Schema to TypeScript Interface

This feature allows you to convert a JSON Schema into a TypeScript interface. The `compile` function takes a JSON Schema and a name for the resulting TypeScript interface, and returns a promise that resolves to the TypeScript code as a string.

const { compile } = require('json-schema-to-typescript');

const schema = {
  title: 'Example Schema',
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['name', 'age']
};

compile(schema, 'ExampleSchema')
  .then(ts => console.log(ts));

Generate TypeScript Definitions from Multiple Schemas

This feature allows you to generate TypeScript definitions from a JSON Schema file. The `compileFromFile` function reads a JSON Schema from a file and returns a promise that resolves to the TypeScript code as a string.

const { compileFromFile } = require('json-schema-to-typescript');

compileFromFile('path/to/schema.json')
  .then(ts => console.log(ts));

Customizing Output

This feature allows you to customize the output of the TypeScript definitions. The `compile` function accepts an options object where you can specify various settings like adding a banner comment to the generated TypeScript code.

const { compile } = require('json-schema-to-typescript');

const schema = {
  title: 'Example Schema',
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' }
  },
  required: ['name', 'age']
};

const options = {
  bannerComment: '/* This is a generated file */'
};

compile(schema, 'ExampleSchema', options)
  .then(ts => console.log(ts));

Other packages similar to json-schema-to-typescript

typescript-json-schema

The typescript-json-schema package generates JSON Schema from your TypeScript types. It works in the opposite direction compared to json-schema-to-typescript, making it useful for projects where you start with TypeScript types and need to generate JSON Schema for validation or documentation purposes.

quicktype

The quicktype package can generate TypeScript types from JSON Schema, JSON data, and other sources. It supports multiple languages and is highly configurable, making it a versatile tool for generating types from various data formats.

json-schema-to-flow-type

The json-schema-to-flow-type package converts JSON Schema to Flow types. While it serves a similar purpose to json-schema-to-typescript, it is specifically designed for projects using Flow instead of TypeScript.

README

json-schema-to-typescript

Compile json schema to typescript typings

Example

Input:

{
  "title": "Example Schema",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "age": {
      "description": "Age in years",
      "type": "integer",
      "minimum": 0
    },
    "hairColor": {
      "enum": ["black", "brown", "blue"],
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": ["firstName", "lastName"]
}

Output:

export interface ExampleSchema {
  firstName: string;
  lastName: string;
  /**
   * Age in years
   */
  age?: number;
  hairColor?: "black" | "brown" | "blue";
}

Installation

# Using Yarn:
yarn add json-schema-to-typescript

# Or, using NPM:
npm install json-schema-to-typescript --save

Usage

import { compile, compileFromFile } from 'json-schema-to-typescript'

// compile from file
compileFromFile('foo.json')
  .then(ts => fs.writeFileSync('foo.d.ts', ts))

// or, compile a JS object
let mySchema = {
  properties: [...]
}
compile(mySchema, 'MySchema')
  .then(ts => ...)

See server demo and browser demo for full examples.

Options

compileFromFile and compile accept options as their last argument (all keys are optional):

key	type	default	description
bannerComment	string	"/* tslint:disable */\n/**\n* This file was automatically generated by json-schema-to-typescript.\n* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,\n* and run json-schema-to-typescript to regenerate this file.\n*/"	Disclaimer comment prepended to the top of each generated file
cwd	string	process.cwd()	Root directory for resolving $refs
declareExternallyReferenced	boolean	true	Declare external schemas referenced via $ref?
enableConstEnums	boolean	true	Prepend enums with const?
ignoreMinAndMaxItems	boolean	false	Ignore maxItems and minItems for array types, preventing tuples being generated.
style	object	{ bracketSpacing: false, printWidth: 120, semi: true, singleQuote: false, tabWidth: 2, trailingComma: 'none', useTabs: false }	A Prettier configuration
unknownAny	boolean	true	Use unknown instead of any where possible
unreachableDefinitions	boolean	false	Generates code for definitions that aren't referenced by the schema.
strictIndexSignatures	boolean	false	Append all index signatures with | undefined so that they are strictly typed.
$refOptions	object	{}	$RefParser Options, used when resolving $refs

CLI

A CLI utility is provided with this package.

cat foo.json | json2ts > foo.d.ts
# or
json2ts foo.json > foo.d.ts
# or
json2ts foo.json foo.d.ts
# or
json2ts --input foo.json --output foo.d.ts
# or
json2ts -i foo.json -o foo.d.ts
# or
json2ts -i schemas/**/*.json
# or
json2ts -i schemas/ -o types/

You can pass any of the options described above (including style options) as CLI flags. Boolean values can be set to false using the no- prefix.

# generate code for definitions that aren't referenced
json2ts -i foo.json -o foo.d.ts --unreachableDefinitions
# use single quotes and disable trailing semicolons
json2ts -i foo.json -o foo.d.ts --style.singleQuote --no-style.semi

Tests

npm test

Features

• title => interface
• Primitive types:
  • array
  • homogeneous array
  • boolean
  • integer
  • number
  • null
  • object
  • string
  • homogeneous enum
  • heterogeneous enum
• Non/extensible interfaces
• Custom JSON-schema extensions
• Nested properties
• Schema definitions
• Schema references
• Local (filesystem) schema references
• External (network) schema references
• Add support for running in browser
• default interface name
• infer unnamed interface name from filename
• allOf ("intersection")
• anyOf ("union")
• oneOf (treated like anyOf)
• maxItems (eg)
• minItems (eg)
• additionalProperties of type
• patternProperties (partial support)
• extends
• required properties on objects (eg)
• validateRequired (eg)
• literal objects in enum (eg)
• referencing schema by id (eg)
• custom typescript types via tsType

Custom schema properties:

• tsType: Overrides the type that's generated from the schema. Useful for forcing a type to any or when using non-standard JSON schema extensions (eg).
• tsEnumNames: Overrides the names used for the elements in an enum. Can also be used to create string enums (eg).

Not expressible in TypeScript:

• dependencies (single, multiple)
• divisibleBy (eg)
• format (eg)
• multipleOf (eg)
• maximum (eg)
• minimum (eg)
• maxProperties (eg)
• minProperties (eg)
• not/disallow
• oneOf ("xor", use anyOf instead)
• pattern (string, regex)
• uniqueItems (eg)

Further Reading

• JSON-schema spec: https://tools.ietf.org/html/draft-zyp-json-schema-04
• JSON-schema wiki: https://github.com/json-schema/json-schema/wiki
• JSON-schema test suite: https://github.com/json-schema/JSON-Schema-Test-Suite/blob/node
• TypeScript spec: https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

Who uses JSON-Schema-to-TypeScript?

• AWS, AWSLabs
• FormatJS
• Microsoft
• Sourcegraph
• Stryker
• Webpack
• See more